﻿/**
 * @file std_list.c
 * Copyright (c) 2019 Gaaagaa. All rights reserved.
 * 
 * @author  : Gaaagaa
 * @date    : 2019-09-09
 * @version : 1.0.0.0
 * @brief   : 使用 C API 的接口形式实现 双向链表 容器。
 */

/**
 * The MIT License (MIT)
 * Copyright (c) Gaaagaa. All rights reserved.
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is furnished to do
 * so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#include "std_list.h"
#include "std_debug.h"
#include "std_list.inl"

////////////////////////////////////////////////////////////////////////////////

#ifdef __GNUC__
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-function"
#endif // __GNUC__

////////////////////////////////////////////////////////////////////////////////

//====================================================================

// 
// xstd_list_t 的内部操作接口
// 

/**********************************************************/
/**
 * @brief 申请链表的 xlst_node_t 对象缓存。
 */
static xlst_iter_t list_node_malloc(xlst_this_t xlst_this)
{
#if XLST_ELEM_SEPARATED

    xlst_iter_t xiter_node = 
        (xlst_iter_t)XLST_MALLOC(xlst_this, sizeof(xlst_node_t));
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_ELEM(xiter_node) = 
        (xlst_elem_t)XLST_MALLOC(xlst_this, XLST_ESIZE(xlst_this));
    XASSERT(XLST_NULL != XLST_ITER_ELEM(xiter_node));

#else // !XLST_ELEM_SEPARATED

    xlst_iter_t xiter_node = 
        (xlst_iter_t)XLST_MALLOC(
            xlst_this, sizeof(xlst_node_t) + XLST_ESIZE(xlst_this));
    XASSERT(XLST_NULL != xiter_node);

#endif // XLST_ELEM_SEPARATED

    xiter_node->xiter_prev =
    xiter_node->xiter_next = XLST_NULL;
#if XLST_CHECKED_OWNER
    xiter_node->xlst_owner = xlst_this;
#endif // XLST_CHECKED_OWNER

    return xiter_node;
}

/**********************************************************/
/**
 * @brief 创建链表的 xlst_node_t 对象。
 * 
 * @param [in ] xlst_this : xstd_list_t 对象。
 * @param [in ] xlst_elem : 节点所存储的元素。
 * 
 * @return xlst_iter_t : xlst_node_t 节点对应的迭代器对象。
 */
static inline xlst_iter_t list_node_alfrom(
                                xlst_this_t xlst_this,
                                xlst_elem_t xlst_elem)
{
    xlst_iter_t xiter_node = list_node_malloc(xlst_this);

    XLST_ALFROM(xlst_this, XLST_ITER_ELEM(xiter_node), xlst_elem);

    return xiter_node;
}

/**********************************************************/
/**
 * @brief 创建链表的 xlst_node_t 对象（使用右值 move 操作进行元素拷贝）。
 * 
 * @param [in ] xlst_this : xstd_list_t 对象。
 * @param [in ] xlst_elem : 节点所存储的元素。
 * 
 * @return xlst_iter_t : xlst_node_t 节点对应的迭代器对象。
 */
static inline xlst_iter_t list_node_almove(
                                xlst_this_t xlst_this,
                                xlst_elem_t xlst_elem)
{
    xlst_iter_t xiter_node = list_node_malloc(xlst_this);

    XLST_ALMOVE(xlst_this, XLST_ITER_ELEM(xiter_node), xlst_elem);

    return xiter_node;
}

/**********************************************************/
/**
 * @brief 销毁链表的 xlst_node_t 对象。
 * 
 * @param [in ] xlst_this  : xstd_list_t 对象。
 * @param [in ] xiter_node : xlst_node_t 节点对应的迭代器对象。
 */
static xlst_void_t list_node_dealloc(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_node)
{
    XLST_ALDEST(xlst_this, XLST_ITER_ELEM(xiter_node));

#if XLST_ELEM_SEPARATED
    XLST_DEALLOC(xlst_this, XLST_ITER_ELEM(xiter_node));
#endif // XLST_ELEM_SEPARATED

    XLST_DEALLOC(xlst_this, xiter_node);
}

/**********************************************************/
/**
 * @brief 判断 迭代器对应节点 是否存在于（隶属于）链表中。
 */
static xlst_bool_t list_node_is_exist(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_node)
{
    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);

    if ((XLST_NULL != xiter_node) && XLST_ITER_ISDOCK(xiter_node))
    {
#if XLST_CHECKED_OWNER
        if (xlst_this != xiter_trav->xlst_owner)
            return XLST_FALSE;
#endif // XLST_CHECKED_OWNER
        while (xiter_trav != XLST_ITER_END(xlst_this))
        {
            if (xiter_trav == xiter_node)
                return XLST_TRUE;
            xiter_trav = xiter_trav->xiter_next;
        }
    }

    return XLST_FALSE;
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象追加多个节点（存储相同元素值）。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xst_count : 添加节点的数量。
 * @param [in    ] xlst_elem : 节点存储的元素。
 */
static xlst_void_t list_node_append(
                        xlst_this_t xlst_this,
                        xlst_size_t xst_count,
                        xlst_elem_t xlst_elem)
{
    xlst_iter_t xiter_node = XLST_NULL;
    xlst_iter_t xiter_head = XLST_NULL;
    xlst_iter_t xiter_tail = XLST_NULL;
    xlst_size_t xst_icount = xst_count;

    if (0 == xst_icount)
    {
        return;
    }

    xiter_node = list_node_alfrom(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    xiter_head = xiter_node;
    xiter_tail = xiter_node;
    --xst_icount;

    while (xst_icount-- > 0)
    {
        xiter_node = list_node_alfrom(xlst_this, xlst_elem);
        XASSERT(XLST_NULL != xiter_node);

        xiter_tail->xiter_next = xiter_node;
        xiter_node->xiter_prev = xiter_tail;
        xiter_tail = xiter_node;
    }

    xiter_head->xiter_prev = XLST_ITER_RBEGIN(xlst_this);
    xiter_tail->xiter_next = XLST_ITER_END(xlst_this);
    XLST_ITER_RBEGIN(xlst_this)->xiter_next = xiter_head;
    XLST_ITER_END(xlst_this)->xiter_prev = xiter_tail;
    xlst_this->xlst_csize += xst_count;
}

/**********************************************************/
/**
 * @brief 判断 xiter_trav 是否在 [ xiter_head, xiter_tail ] 链表区间内。
 * @note  判断得到结果前，[ xiter_head, xiter_tail ] 必须是有效区间。
 */
static xlst_bool_t list_iter_in_scope(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_trav,
                        xlst_iter_t xiter_head,
                        xlst_iter_t xiter_tail)
{
    if ((XLST_NULL != xiter_trav) && XLST_ITER_ISDOCK(xiter_trav))
    {
#if XLST_CHECKED_OWNER
        if (xlst_this != xiter_trav->xlst_owner)
            return XLST_FALSE;
#endif // XLST_CHECKED_OWNER
        for (;;)
        {
            if (xiter_head == xiter_trav)
                return XLST_TRUE;
            if (xiter_head == xiter_tail)
                break;
            xiter_head = xiter_head->xiter_next;
        }
    }

    return XLST_FALSE;
}

/**********************************************************/
/**
 * @brief 判断 迭代器 对应节点是否在 链表中。
 */
static inline xlst_bool_t list_iter_is_exist(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_trav)
{
    return list_iter_in_scope(
                    xlst_this,
                    xiter_trav,
                    XLST_ITER_BEGIN(xlst_this),
                    XLST_ITER_END(xlst_this));
}

/**********************************************************/
/**
 * @brief 判断 迭代器 对应节点是否在指定节点的右侧。
 */
static inline xlst_bool_t list_iter_in_right(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_trav,
                        xlst_iter_t xiter_wpos)
{
    return list_iter_in_scope(
                    xlst_this,
                    xiter_trav,
                    xiter_wpos,
                    XLST_ITER_END(xlst_this));
}

/**********************************************************/
/**
 * @brief 删除链表 [ xiter_first, xiter_last ) 区间内的节点。
 */
static xlst_void_t list_range_erase(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_first,
                        xlst_iter_t xiter_last)
{
    xlst_size_t xst_icount = 0;

    if (xiter_first != xiter_last)
    {
        xiter_first->xiter_prev->xiter_next = xiter_last;
        xiter_last->xiter_prev = xiter_first->xiter_prev;

        do
        {
            xiter_first = xiter_first->xiter_next;
            list_node_dealloc(xlst_this, xiter_first->xiter_prev);
            ++xst_icount;
        } while (xiter_first != xiter_last);

        xlst_this->xlst_csize -= xst_icount;
    }
}

/**********************************************************/
/**
 * @brief 判断链表的区间 [ xiter_first, xiter_last) 是否已排序。
 */
static xlst_bool_t list_range_is_sorted(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_first,
                        xlst_iter_t xiter_last,
                        xlst_cmpfunc_t xfunc_cmp)
{
    if (xiter_first != xiter_last)
    {
        for (; xiter_first->xiter_next != xiter_last;
               xiter_first = xiter_first->xiter_next)
        {
            if (xfunc_cmp(
                    XLST_ITER_ELEM(xiter_first->xiter_next),
                    XLST_ITER_ELEM(xiter_first),
                    XLST_ECTXT(xlst_this)))
            {
                return XLST_FALSE;
            }
        }
    }

    return XLST_TRUE;
}

/** 用于判断 xstd_list_t 对象是否已排序的宏函数 */
#define XLIST_IS_SORTED(xlst_this, xfunc_cmp) \
    list_range_is_sorted(                     \
        (xlst_this), XLST_ITER_BEGIN(xlst_this), XLST_ITER_END(xlst_this), (xfunc_cmp))

/**********************************************************/
/**
 * @brief 
 * 对链表区间 [ xiter_first, xiter_last ) 进行重排序操作，
 * 其中 [ xiter_first, xiter_mid ) 和 [ xiter_mid, xiter_last ) 已排序。
 * @note 归并排序算法的归并辅助操作。
 * 
 * @param [in ] xlst_this   : xstd_list_t 对象。
 * @param [in ] xiter_first : 重排序区间的起始位置。
 * @param [in ] xiter_mid   : 重排序区间的中部位置。
 * @param [in ] xiter_last  : 重排序区间的结束位置。
 * @param [in ] xfunc_cmp   : 节点比较（小于）判断的回调函数。
 * 
 * @return xlst_iter_t : 
 * 返回 [ xiter_first, xiter_last ) 重排序后的起始位置（迭代器）。
 */
static xlst_iter_t list_range_merge_same(
                        xlst_this_t xlst_this,
                        xlst_iter_t xiter_first,
                        xlst_iter_t xiter_mid,
                        xlst_iter_t xiter_last,
                        xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT((xiter_first != xiter_mid) && (xiter_mid != xiter_last));

    xlst_iter_t xiter_head = XLST_NULL;
    xlst_iter_t xiter_trav = XLST_NULL;
    xlst_iter_t xiter_swap = XLST_NULL;

    if (xfunc_cmp(
            XLST_ITER_ELEM(xiter_mid),
            XLST_ITER_ELEM(xiter_first),
            XLST_ECTXT(xlst_this)))
    {
        xiter_head = xiter_mid;
    }
    else
    {
        xiter_head = xiter_first;
        do
        {
            xiter_first = xiter_first->xiter_next;
            if (xiter_first == xiter_mid)
            {
                return xiter_head;
            }
        } while (
            !xfunc_cmp(
                XLST_ITER_ELEM(xiter_mid),
                XLST_ITER_ELEM(xiter_first),
                XLST_ECTXT(xlst_this)));
    }

    for (;;)
    {
        xiter_trav = xiter_mid;
        do
        {
            xiter_mid = xiter_mid->xiter_next;
            if (xiter_mid == xiter_last)
                break;
        } while (
            xfunc_cmp(
                XLST_ITER_ELEM(xiter_mid),
                XLST_ITER_ELEM(xiter_first),
                XLST_ECTXT(xlst_this)));

        XLST_ITER_SPLICE(xiter_first, xiter_trav, xiter_mid, xiter_swap);
        if (xiter_mid == xiter_last)
        {
            return xiter_head;
        }

        do
        {
            xiter_first = xiter_first->xiter_next;
            if (xiter_first == xiter_mid)
            {
                return xiter_head;
            }
        } while (
            !xfunc_cmp(
                XLST_ITER_ELEM(xiter_mid),
                XLST_ITER_ELEM(xiter_first),
                XLST_ECTXT(xlst_this)));
    }

    // never run to here
    XASSERT(XLST_FALSE);

    return xiter_head;
}

/**********************************************************/
/**
 * @brief 对链表的区间 [ xiter_first, xiter_first + xst_rsize) 进行排序操作。
 * @note  此接口实现的是归并排序算法，以递归方式进行排序操作。
 * 
 * @param [in ] xlst_this   : xstd_list_t 对象。
 * @param [in ] xiter_first : 排序区间的起始位置。
 * @param [in ] xst_rsize   : 排序区间的节点数量。
 * @param [in ] xfunc_cmp   : 节点比较（小于）判断的回调函数。
 * 
 * @return xlst_iter_t : 
 * 返回 xiter_first + xst_rsize 所指向的节点位置（迭代器）。
 */
static xlst_iter_t list_range_merge_sort(
                        xlst_this_t xlst_this,
                        xlst_iter_t * xiter_first,
                        xlst_size_t xst_rsize,
                        xlst_cmpfunc_t xfunc_cmp)
{
    if (0 == xst_rsize) return (*xiter_first);
    if (1 == xst_rsize) return (*xiter_first)->xiter_next;

    xlst_iter_t xiter_mid =
        list_range_merge_sort(
            xlst_this, xiter_first, xst_rsize / 2, xfunc_cmp);

    xlst_iter_t xiter_last =
        list_range_merge_sort(
            xlst_this, &xiter_mid, xst_rsize - xst_rsize / 2, xfunc_cmp);

    (*xiter_first) =
        list_range_merge_same(
            xlst_this, *xiter_first, xiter_mid, xiter_last, xfunc_cmp);

    return xiter_last;
}

//====================================================================

// 
// xstd_list_t 的外部操作接口
// 

/**********************************************************/
/**
 * @brief 返回内部的 sizeof(xstd_list_t) 值。
 */
xlst_size_t std_list_sizeof(void)
{
    return (xlst_size_t)sizeof(xstd_list_t);
}

/**********************************************************/
/**
 * @brief 创建 xstd_list_t 对象。
 * @note 
 * 1. 入参 xlst_ctxt 中的 内存管理对象，若其中的某个回调函数
 *    为 XLST_NULL，则配置成全局管理对象对应函数接口。
 * 2. 可使用 @see std_list_destroy() 销毁对象。
 * 
 * @param [in ] xlst_ctxt : 链表所存储节点的类型上下文描述信息。
 * 
 * @return xlst_this_t : xstd_list_t 对象指针。
 */
xlst_this_t std_list_create(xlst_ctxt_t xlst_ctxt)
{
    XASSERT(0 != xlst_ctxt);
    XASSERT(0 != xlst_ctxt->xstd_etype);
    XASSERT(0 != xlst_ctxt->xstd_esize);

    xstd_altor_t xstd_altor = XSTD_ALTOR_NCREF(xlst_ctxt->xstd_altor);
    xlst_this_t xlst_this =
        (xlst_this_t)xstd_altor->xfunc_allocate(sizeof(xstd_list_t));
    XASSERT(XLST_NULL != xlst_this);

    return std_list_emplace_create(xlst_this, xlst_ctxt);
}

/**********************************************************/
/**
 * @brief 销毁 xstd_list_t 对象，其由 @see std_list_create() 创建。
 */
xlst_void_t std_list_destroy(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);

    xstd_altor_t xstd_altor = XLST_ALTOR(xlst_this);

    std_list_emplace_destroy(xlst_this);
    xstd_altor->xfunc_dealloc(xlst_this);
}

/**********************************************************/
/**
 * @brief 创建 xstd_list_t 对象。
 * @note 
 * 1. 入参 xlst_ctxt 中的 内存管理对象，若其中的某个回调函数
 *    为 XLST_NULL，则配置成全局管理对象对应函数接口。
 * 2. 可使用 @see std_list_emplace_destroy() 销毁对象。
 * 
 * @param [in,out] xlst_this : 
 * 存储 xstd_list_t 对象的缓存，
 * 其大小不可小于 std_list_sizeof() 的返回值。
 * 
 * @param [in    ] xlst_ctxt : 链表所存储节点的类型上下文描述信息。
 * 
 * @return xlst_this_t : xstd_list_t 对象指针。
 */
xlst_this_t std_list_emplace_create(
                xlst_this_t xlst_this,
                xlst_ctxt_t xlst_ctxt)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_ctxt);
    XASSERT(0 != xlst_ctxt->xstd_etype);
    XASSERT(0 != xlst_ctxt->xstd_esize);

    //======================================

    XLST_ECTXT_UPDATE(xlst_this, xlst_ctxt);

    xlst_this->xlst_csize = 0;
    XLST_RESET_ENTRY(xlst_this);

#if XLST_CHECKED_OWNER
    xlst_this->xlst_entry.xlst_owner = xlst_this;
#endif // XLST_CHECKED_OWNER

    //======================================

    return xlst_this;
}

/**********************************************************/
/**
 * @brief 在指定缓存上销毁 xstd_list_t 对象。
 * @note  xstd_list_t 对象是由 @see std_list_emplace_create() 创建。
 */
xlst_void_t std_list_emplace_destroy(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    std_list_clear(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的 上下文信息。
 */
xlst_ctxt_t std_list_ctxt(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ECTXT(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的 类型标识。
 */
xlst_size_t std_list_etype(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ETYPE(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象中的节点数量。
 */
xlst_size_t std_list_size(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 判断 xstd_list_t 对象是否为空。
 */
xlst_bool_t std_list_empty(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return (0 == xlst_this->xlst_csize);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象可容纳最大节点数量。
 */
xlst_size_t std_list_maxsize(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_MAX_SIZE(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的前端节点值。
 */
xlst_elem_t std_list_front(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(0 != xlst_this->xlst_csize);

    return XLST_ITER_ELEM(XLST_ITER_BEGIN(xlst_this));
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的后端节点值。
 */
xlst_elem_t std_list_back(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(0 != xlst_this->xlst_csize);

    return XLST_ITER_ELEM(XLST_ITER_RBEGIN(xlst_this));
}

/**********************************************************/
/**
 * @brief 清除 xstd_list_t 对象中的所有节点。
 */
xlst_void_t std_list_clear(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);

    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);
    xlst_iter_t xiter_last = XLST_ITER_RBEGIN(xlst_this);

    if (xlst_this->xlst_csize > 0)
    {
        XLST_RESET_ENTRY(xlst_this);
        xlst_this->xlst_csize = 0;

        for (;;)
        {
            if (xiter_trav == xiter_last)
            {
                list_node_dealloc(xlst_this, xiter_trav);
                break;
            }

            xiter_trav = xiter_trav->xiter_next;
            list_node_dealloc(xlst_this, xiter_trav->xiter_prev);
        }
    }
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象插入新的节点。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xiter_pos : 插入节点的所在位置。
 * @param [in    ] xlst_elem : 插入节点的所存储元素。
 * 
 * @return xlst_iter_t : 返回新插入节点对应的迭代器。
 */
xlst_iter_t std_list_insert(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    HASSERT(list_iter_is_exist(xlst_this, xiter_pos));
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_alfrom(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(xiter_pos, xiter_node);
    ++xlst_this->xlst_csize;

    return xiter_node;
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象安放新的节点，元素以 右值move 方式进行存储。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xiter_pos : 安放新节点的所在位置。
 * @param [in    ] xlst_elem : 安放新节点的所存储元素。
 * 
 * @return xlst_iter_t : 返回新安放节点对应的迭代器。
 */
xlst_iter_t std_list_emplace(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    HASSERT(list_iter_is_exist(xlst_this, xiter_pos));
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_almove(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(xiter_pos, xiter_node);
    ++xlst_this->xlst_csize;

    return xiter_node;
}

/**********************************************************/
/**
 * @brief 从 xstd_list_t 对象中删除指定的节点。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xiter_pos : 删除节点的所在位置。
 * 
 * @return xlst_iter_t : 返回 xiter_pos 的后继节点迭代器。
 */
xlst_iter_t std_list_erase(xlst_this_t xlst_this, xlst_iter_t xiter_pos)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xiter_pos);
    XASSERT(xiter_pos != XLST_ITER_END(xlst_this));
    HASSERT(list_node_is_exist(xlst_this, xiter_pos));

    xlst_iter_t xiter_next = xiter_pos->xiter_next;

    XLST_ITER_RMNODE(xiter_pos);
    list_node_dealloc(xlst_this, xiter_pos);
    --xlst_this->xlst_csize;

    return xiter_next;
}

/**********************************************************/
/**
 * @brief 从 xstd_list_t 对象中删除 [ xiter_first, xiter_last ) 子串。
 * 
 * @param [in,out] xlst_this   : xstd_list_t 对象。
 * @param [in    ] xiter_first : 迭代区域的起始位置。
 * @param [in    ] xiter_last  : 迭代区域的结束位置。
 * 
 * @return xlst_iter_t : 返回 xiter_last 迭代器。
 */
xlst_iter_t std_list_erase_range(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_first,
                xlst_iter_t xiter_last)
{
    XASSERT(XLST_NULL != xlst_this);
    HASSERT(list_iter_is_exist(xlst_this, xiter_first));
    HASSERT(list_iter_in_right(xlst_this, xiter_last, xiter_first));

    list_range_erase(xlst_this, xiter_first, xiter_last);
    return xiter_last;
}

/**********************************************************/
/**
 * @brief 将 多个（相同的）节点值 指派给 xstd_list_t 对象。
 * @note  该操作会更新整个 xstd_list_t 对象，包括节点数量。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xlst_size : 指派的节点数量。
 * @param [in    ] xlst_elem : 指派的节点值。
 */
xlst_void_t std_list_assign(
                xlst_this_t xlst_this,
                xlst_size_t xlst_size,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(xlst_size <= XLST_MAX_SIZE(xlst_this));
    XASSERT((0 == xlst_size) || (XLST_NULL != xlst_elem));

    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);

#if 0
    for (;;)
    {
        if (xiter_trav == XLST_ITER_END(xlst_this))
        {
            list_node_append(xlst_this, xlst_size, xlst_elem);
            break;
        }

        if (0 == xlst_size)
        {
            list_range_erase(xlst_this, xiter_trav, XLST_ITER_END(xlst_this));
            break;
        }

        XLST_ALDEST(xlst_this, XLST_ITER_ELEM(xiter_trav));
        XLST_ALFROM(xlst_this, XLST_ITER_ELEM(xiter_trav), xlst_elem);
        xiter_trav = xiter_trav->xiter_next;
        --xlst_size;
    }
#else
    if (xlst_size == xlst_this->xlst_csize)
    {
        while (xiter_trav != XLST_ITER_END(xlst_this))
        {
            XLST_ALDEST(xlst_this, XLST_ITER_ELEM(xiter_trav));
            XLST_ALFROM(xlst_this, XLST_ITER_ELEM(xiter_trav), xlst_elem);
            xiter_trav = xiter_trav->xiter_next;
        }
    }
    else if (xlst_size > xlst_this->xlst_csize)
    {
        while (xiter_trav != XLST_ITER_END(xlst_this))
        {
            XLST_ALDEST(xlst_this, XLST_ITER_ELEM(xiter_trav));
            XLST_ALFROM(xlst_this, XLST_ITER_ELEM(xiter_trav), xlst_elem);
            xiter_trav = xiter_trav->xiter_next;
        }

        list_node_append(
            xlst_this, xlst_size - xlst_this->xlst_csize, xlst_elem);
    }
    else
    {
        while (xlst_size-- > 0)
        {
            XLST_ALDEST(xlst_this, XLST_ITER_ELEM(xiter_trav));
            XLST_ALFROM(xlst_this, XLST_ITER_ELEM(xiter_trav), xlst_elem);
            xiter_trav = xiter_trav->xiter_next;
        }

        list_range_erase(xlst_this, xiter_trav, XLST_ITER_END(xlst_this));
    }
#endif
}

/**********************************************************/
/**
 * @brief
 * 调整 xstd_list_t 对象中的节点数量到 指定值。
 * 若 指定值 多于原有的节点数量，则使用 指定节点元素 补充多出的节点。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xlst_size : 所要调整到的节点数量。
 * @param [in    ] xlst_elem : 补充操作时使用的节点元素。
 */
xlst_void_t std_list_resize(
                xlst_this_t xlst_this,
                xlst_size_t xlst_size,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_size < XLST_MAX_SIZE(xlst_this));

    if (xlst_size > xlst_this->xlst_csize)
    {
        list_node_append(
            xlst_this, xlst_size - xlst_this->xlst_csize, xlst_elem);
    }
    else
    {
        while (xlst_size < xlst_this->xlst_csize)
        {
            std_list_pop_back(xlst_this);
        }
    }
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象前端新增一个节点。
 */
xlst_void_t std_list_push_front(
                xlst_this_t xlst_this,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_alfrom(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(XLST_ITER_BEGIN(xlst_this), xiter_node);
    ++xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象前端新增一个节点，元素以 右值move 方式进行存储。
 */
xlst_void_t std_list_push_mfront(
                xlst_this_t xlst_this,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_almove(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(XLST_ITER_BEGIN(xlst_this), xiter_node);
    ++xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 将 xstd_list_t 对象的前端节点弹出（删除）。
 */
xlst_void_t std_list_pop_front(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(0 != xlst_this->xlst_csize);

    xlst_iter_t xiter_node = XLST_ITER_BEGIN(xlst_this);
    XLST_ITER_RMNODE(xiter_node);
    list_node_dealloc(xlst_this, xiter_node);
    --xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象后端新增一个节点。
 */
xlst_void_t std_list_push_back(
                xlst_this_t xlst_this,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_alfrom(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(XLST_ITER_END(xlst_this), xiter_node);
    ++xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 向 xstd_list_t 对象后端新增一个节点，元素以 右值move 方式进行存储。
 */
xlst_void_t std_list_push_mback(
                xlst_this_t xlst_this,
                xlst_elem_t xlst_elem)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(xlst_this->xlst_csize < XLST_MAX_SIZE(xlst_this));

    xlst_iter_t xiter_node = list_node_almove(xlst_this, xlst_elem);
    XASSERT(XLST_NULL != xiter_node);

    XLST_ITER_INSERT(XLST_ITER_END(xlst_this), xiter_node);
    ++xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 将 xstd_list_t 对象的后端节点弹出（删除）。
 */
xlst_void_t std_list_pop_back(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(0 != xlst_this->xlst_csize);

    xlst_iter_t xiter_node = XLST_ITER_RBEGIN(xlst_this);
    XLST_ITER_RMNODE(xiter_node);
    list_node_dealloc(xlst_this, xiter_node);
    --xlst_this->xlst_csize;
}

/**********************************************************/
/**
 * @brief 对 xstd_list_t 对象进行反序操作。
 */
xlst_void_t std_list_reverse(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);

    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);
    xlst_iter_t xiter_next = XLST_NULL;

    for (;;)
    {
        xiter_next = xiter_trav->xiter_next;

        xiter_trav->xiter_next = xiter_trav->xiter_prev;
        xiter_trav->xiter_prev = xiter_next;

        if (xiter_trav == XLST_ITER_END(xlst_this))
            break;

        xiter_trav = xiter_next;
    }
}

/**********************************************************/
/**
 * @brief 
 * 将 xstd_list_t 对象中的区间 [ xiter_first, xiter_last ) 
 * 切换至指定位置。
 * @note 
 * 所指定的目标位置 xiter_pos 不能
 * 位于 [ xiter_first, xiter_last ) 区间内。
 * 
 * @param [in,out] xlst_this   : xstd_list_t 对象。
 * @param [in    ] xiter_pos   : 切换所至的目标位置。
 * @param [in    ] xiter_first : 子串区间的起始位置。
 * @param [in    ] xiter_last  : 子串区间的结束位置。
 */
xlst_void_t std_list_splice(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_iter_t xiter_first,
                xlst_iter_t xiter_last)
{
    XASSERT(XLST_NULL != xlst_this  );
    XASSERT(XLST_NULL != xiter_pos  );
    XASSERT(XLST_NULL != xiter_first);
    XASSERT(XLST_NULL != xiter_last );

    HASSERT(list_iter_is_exist(xlst_this, xiter_first));
    HASSERT(list_iter_in_right(xlst_this, xiter_last, xiter_first));

    xlst_iter_t xiter_swap = XLST_NULL;

    if (xiter_first == xiter_last)
        return;
    if ((xiter_pos == xiter_first) || (xiter_pos == xiter_last))
        return;
    HASSERT(!list_iter_in_scope(xlst_this, xiter_pos, xiter_first, xiter_last));

    XLST_ITER_SPLICE(xiter_pos, xiter_first, xiter_last, xiter_swap);
}

/**********************************************************/
/**
 * @brief 
 * 将另一同类型的 xlst_other 对象内的所有节点拼接到
 * 现有的 xlst_this 对象中指定位置。
 * @note 
 * xlst_this 与 xlst_other 的 类型标识 与 节点元素类型 必须一致。
 * 操作完成后，xlst_other 将会被清空。
 * 
 * @param [in,out] xlst_this  : xstd_list_t 对象。
 * @param [in    ] xiter_pos  : 拼接位置（xlst_this 中的节点位置）。
 * @param [in,out] xlst_other : 另一同类型的 xstd_list_t 对象。
 */
xlst_void_t std_list_splice_other(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_this_t xlst_other)
{
    XASSERT(XLST_NULL != xlst_this);
    HASSERT(list_iter_is_exist(xlst_this, xiter_pos));
    XASSERT(XLST_NULL != xlst_other);
    XASSERT(XLST_ISSAME_TYPE(xlst_this, xlst_other));

    xlst_iter_t xiter_trav = XLST_NULL;

    if ((xlst_this == xlst_other) || (0 == xlst_other->xlst_csize))
    {
        return;
    }

    XASSERT((XLST_MAX_SIZE(xlst_this) - xlst_this->xlst_csize) >= xlst_other->xlst_csize);

#if XLST_CHECKED_OWNER
    for (xiter_trav = XLST_ITER_BEGIN(xlst_other);
         xiter_trav != XLST_ITER_END(xlst_other);
         xiter_trav = xiter_trav->xiter_next)
    {
        xiter_trav->xlst_owner = xlst_this;
    }
#endif // XLST_CHECKED_OWNER

    xlst_this->xlst_csize += xlst_other->xlst_csize;
    xlst_other->xlst_csize = 0;

    XLST_ITER_SPLICE(
        xiter_pos,
        XLST_ITER_BEGIN(xlst_other),
        XLST_ITER_END(xlst_other),
        xiter_trav);
}

/**********************************************************/
/**
 * @brief 
 * 将另一同类型的 xlst_other 对象内的 （区间）节点子串
 * 拼接到现有的 xlst_this 对象中。
 * @note 
 * 1. xlst_this 与 xlst_other 的 类型标识 与 节点元素类型 必须一致。
 * 2. 若 xlst_this != xlst_other 时，
 *    xlst_other的（区间）节点子串 将会被转移到 xlst_this 中。
 * 3. 若 xlst_this == xlst_other 时，
 *    则要求 xiter_pos 必须在区间 [ xiter_first, xiter_last ) 之外。
 * 
 * @param [in,out] xlst_this   : xstd_list_t 对象。
 * @param [in    ] xiter_pos   : 拼接位置（xlst_this 中的节点位置）。
 * @param [in,out] xlst_other  : 另一同类型的 xstd_list_t 对象
 * @param [in    ] xiter_first : xlst_other 的子串区间的起始位置。
 * @param [in    ] xiter_last  : xlst_other 的子串区间的结束位置。
 */
xlst_void_t std_list_splice_range(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_this_t xlst_other,
                xlst_iter_t xiter_first,
                xlst_iter_t xiter_last)
{
    XASSERT(XLST_NULL != xlst_this  );
    XASSERT(XLST_NULL != xiter_pos  );
    XASSERT(XLST_NULL != xlst_other );
    XASSERT(XLST_NULL != xiter_first);
    XASSERT(XLST_NULL != xiter_last );

    XASSERT(XLST_ISSAME_TYPE(xlst_this, xlst_other));
    HASSERT(list_iter_is_exist(xlst_this, xiter_pos));
    HASSERT(list_iter_is_exist(xlst_other, xiter_first));
    HASSERT(list_iter_in_right(xlst_other, xiter_last, xiter_first));

    xlst_iter_t xiter_trav = XLST_NULL;
    xlst_size_t xst_icount = 0;

    if (xiter_first == xiter_last)
        return;

    if (xlst_this == xlst_other)
    {
        if ((xiter_pos == xiter_first) || (xiter_pos == xiter_last))
            return;
        HASSERT(!list_iter_in_scope(xlst_this, xiter_pos, xiter_first, xiter_last));
    }
    else
    {
        if ((xiter_first == XLST_ITER_BEGIN(xlst_other)) &&
            (xiter_last == XLST_ITER_END(xlst_other)))
        {
#if XLST_CHECKED_OWNER
            for (xiter_trav = xiter_first;
                 xiter_trav != xiter_last;
                 xiter_trav = xiter_trav->xiter_next)
            {
                xiter_trav->xlst_owner = xlst_this;
            }
#endif // XLST_CHECKED_OWNER
            xst_icount = xlst_other->xlst_csize;
        }
        else
        {
            for (xiter_trav = xiter_first;
                 xiter_trav != xiter_last;
                 xiter_trav = xiter_trav->xiter_next)
            {
#if XLST_CHECKED_OWNER
                xiter_trav->xlst_owner = xlst_this;
#endif // XLST_CHECKED_OWNER
                ++xst_icount;
            }
        }

        XASSERT((XLST_MAX_SIZE(xlst_this) - xlst_this->xlst_csize) >= xst_icount);
        xlst_this->xlst_csize  += xst_icount;
        xlst_other->xlst_csize -= xst_icount;
    }

    XLST_ITER_SPLICE(xiter_pos, xiter_first, xiter_last, xiter_trav);
}

/**********************************************************/
/**
 * @brief 对 xstd_list_t 对象进行排序操作。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xfunc_cmp : 进行比较（小于）判断的回调函数。
 */
xlst_void_t std_list_sort(
                xlst_this_t xlst_this,
                xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xfunc_cmp);

    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);

    list_range_merge_sort(
        xlst_this, &xiter_trav, xlst_this->xlst_csize, xfunc_cmp);
}

/**********************************************************/
/**
 * @brief 把两个已排序好的 xstd_list_t 对象合并到 xlst_this 中。
 * @note 
 * 1. 合并操作，会把 xlst_other 对象内所有节点转移至 xlst_this 中。
 * 2. 该操作，要求两个链表对象是已排序的，若未排序，则结果不可预测。
 * 
 * @param [in,out] xlst_this  : 被移入节点的 xstd_list_t 对象。
 * @param [in,out] xlst_other : 被移出节点的 xstd_list_t 对象。
 * @param [in    ] xfunc_cmp  : 进行比较（小于）判断的回调函数。
 */
xlst_void_t std_list_merge(
                xlst_this_t xlst_this,
                xlst_this_t xlst_other,
                xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_other);
    XASSERT(XLST_NULL != xfunc_cmp);
    XASSERT(XLST_ISSAME_TYPE(xlst_this, xlst_other));

    xlst_iter_t xiter_trav = XLST_NULL;

    if ((xlst_this == xlst_other) || (0 == xlst_other->xlst_csize))
    {
        return;
    }

    XASSERT((XLST_MAX_SIZE(xlst_this) - xlst_this->xlst_csize) >= xlst_other->xlst_csize);
    XASSERT(XLIST_IS_SORTED(xlst_this , xfunc_cmp));
    XASSERT(XLIST_IS_SORTED(xlst_other, xfunc_cmp));

#if XLST_CHECKED_OWNER
    for (xiter_trav = XLST_ITER_BEGIN(xlst_other);
         xiter_trav != XLST_ITER_END(xlst_other);
         xiter_trav = xiter_trav->xiter_next)
    {
        xiter_trav->xlst_owner = xlst_this;
    }
#endif // XLST_CHECKED_OWNER

    xiter_trav = XLST_ITER_BEGIN(xlst_other);

    XLST_ITER_RBEGIN(xlst_this)->xiter_next = xiter_trav;
    xiter_trav->xiter_prev = XLST_ITER_RBEGIN(xlst_this);
    XLST_ITER_RBEGIN(xlst_this) = XLST_ITER_RBEGIN(xlst_other);

    xlst_this->xlst_csize += xlst_other->xlst_csize;
    xlst_other->xlst_csize = 0;
    XLST_RESET_ENTRY(xlst_other);

    if (xiter_trav != XLST_ITER_BEGIN(xlst_this))
    {
        list_range_merge_same(
            xlst_this,
            XLST_ITER_BEGIN(xlst_this),
            xiter_trav,
            XLST_ITER_END(xlst_this),
            xfunc_cmp);
    }
}

/**********************************************************/
/**
 * @brief 
 * 从 xstd_list_t 对象中移除 移除所有连续重复的节点元素。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xfunc_cmp : 进行比较（等于）判断的回调函数。
 * 
 * @return xlst_size_t : 被移除的节点数量。
 */
xlst_size_t std_list_unique(
                xlst_this_t xlst_this,
                xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xfunc_cmp);

    xlst_size_t xlst_csize = xlst_this->xlst_csize;
    xlst_iter_t xiter_prev = XLST_ITER_BEGIN(xlst_this);
    xlst_iter_t xiter_node = xiter_prev->xiter_next;

    while (xiter_node != XLST_ITER_END(xlst_this))
    {
        if (xfunc_cmp(
                XLST_ITER_ELEM(xiter_prev),
                XLST_ITER_ELEM(xiter_node),
                XLST_ECTXT(xlst_this)))
        {
            XLST_ITER_RMNODE(xiter_node);
            list_node_dealloc(xlst_this, xiter_node);
            --xlst_this->xlst_csize;
        }
        else
        {
            xiter_prev = xiter_node;
        }

        xiter_node = xiter_prev->xiter_next;
    }

    return (xlst_csize - xlst_this->xlst_csize);
}

/**********************************************************/
/**
 * @brief 在 xstd_list_t 对象中查找出现指定 元素 的首个节点。
 * 
 * @param [in ] xlst_this : xstd_list_t 对象。
 * @param [in ] xiter_pos : 查找操作的起始位置。
 * @param [in ] xlst_elem : 指定查找的 元素。
 * @param [in ] xfunc_cmp : 进行比较（等于）判断的回调函数。
 * 
 * @return xlst_iter_t : 
 * 返回对应的节点迭代器，失败时（未找到），返回链表的末端迭代器。
 */
xlst_iter_t std_list_find(
                xlst_this_t xlst_this,
                xlst_iter_t xiter_pos,
                xlst_elem_t xlst_elem,
                xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT(XLST_NULL != xlst_this);
    HASSERT(list_iter_is_exist(xlst_this, xiter_pos));
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(XLST_NULL != xfunc_cmp);

    while (xiter_pos != XLST_ITER_END(xlst_this))
    {
        if (xfunc_cmp(XLST_ITER_ELEM(xiter_pos), xlst_elem, XLST_ECTXT(xlst_this)))
            return xiter_pos;
        xiter_pos = xiter_pos->xiter_next;
    }

    return xiter_pos;
}

/**********************************************************/
/**
 * @brief 从 xstd_list_t 对象中移除与指定元素值相等的节点。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xlst_elem : 指定要移除的元素值。
 * @param [in    ] xfunc_cmp : 进行比较（等于）判断的回调函数。
 * 
 * @return xlst_size_t : 返回被移除节点的数量。
 */
xlst_size_t std_list_remove(
                xlst_this_t xlst_this,
                xlst_elem_t xlst_elem,
                xlst_cmpfunc_t xfunc_cmp)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xlst_elem);
    XASSERT(XLST_NULL != xfunc_cmp);

    xlst_size_t xlst_csize = xlst_this->xlst_csize;
    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);
    xlst_iter_t xiter_next = XLST_NULL;

    while (xiter_trav != XLST_ITER_END(xlst_this))
    {
        if (xfunc_cmp(XLST_ITER_ELEM(xiter_trav), xlst_elem, XLST_ECTXT(xlst_this)))
        {
            xiter_next = xiter_trav->xiter_next;

            XLST_ITER_RMNODE(xiter_trav);
            list_node_dealloc(xlst_this, xiter_trav);
            --xlst_this->xlst_csize;

            xiter_trav = xiter_next;
        }
        else
        {
            xiter_trav = xiter_trav->xiter_next;
        }
    }

    return (xlst_csize - xlst_this->xlst_csize);
}

/**********************************************************/
/**
 * @brief 
 * 从 xstd_list_t 对象中移除 满足特定条件（使用回调函数进行判断）的节点。
 * 
 * @param [in,out] xlst_this : xstd_list_t 对象。
 * @param [in    ] xfunc_cfm : 进行条件判断的回调函数。
 * 
 * @return xlst_size_t : 返回被移除节点的数量。
 */
xlst_size_t std_list_remove_if(
                xlst_this_t xlst_this,
                xlst_cfmfunc_t xfunc_cfm)
{
    XASSERT(XLST_NULL != xlst_this);
    XASSERT(XLST_NULL != xfunc_cfm);

    xlst_size_t xlst_csize = xlst_this->xlst_csize;
    xlst_iter_t xiter_trav = XLST_ITER_BEGIN(xlst_this);
    xlst_iter_t xiter_next = XLST_NULL;

    while (xiter_trav != XLST_ITER_END(xlst_this))
    {
        if (xfunc_cfm(XLST_ITER_ELEM(xiter_trav), XLST_ECTXT(xlst_this)))
        {
            xiter_next = xiter_trav->xiter_next;

            XLST_ITER_RMNODE(xiter_trav);
            list_node_dealloc(xlst_this, xiter_trav);
            --xlst_this->xlst_csize;

            xiter_trav = xiter_next;
        }
        else
        {
            xiter_trav = xiter_trav->xiter_next;
        }
    }

    return (xlst_csize - xlst_this->xlst_csize);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的起始节点迭代器。
 */
xlst_iter_t std_list_begin(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ITER_BEGIN(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 迭代器 的后继节点迭代器。
 */
xlst_iter_t std_list_next(xlst_iter_t xiter_trav)
{
    XASSERT(XLST_NULL != xiter_trav);
    return xiter_trav->xiter_next;
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的结束节点迭代器。
 */
xlst_iter_t std_list_end(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ITER_END(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的反向起始节点迭代器。
 */
xlst_iter_t std_list_rbegin(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ITER_RBEGIN(xlst_this);
}

/**********************************************************/
/**
 * @brief 返回 反向迭代器 的后继节点迭代器。
 */
xlst_iter_t std_list_rnext(xlst_iter_t xiter_trav)
{
    XASSERT(XLST_NULL != xiter_trav);
    return xiter_trav->xiter_prev;
}

/**********************************************************/
/**
 * @brief 返回 xstd_list_t 对象的反向结束节点迭代器。
 */
xlst_iter_t std_list_rend(xlst_this_t xlst_this)
{
    XASSERT(XLST_NULL != xlst_this);
    return XLST_ITER_REND(xlst_this);
}

/**********************************************************/
/**
 * @brief 读取节点迭代器下存储的 元素。
 */
xlst_elem_t std_list_elem(xlst_iter_t xiter_node)
{
    XASSERT(XLST_NULL != xiter_node);
    return XLST_ITER_ELEM(xiter_node);
}

////////////////////////////////////////////////////////////////////////////////

#ifdef __GNUC__
#pragma GCC diagnostic pop
#endif // __GNUC__

////////////////////////////////////////////////////////////////////////////////
